<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en-US">
<head>
<!-- GenHTML revision 25226-->
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<title>Overview of the Second-Level Cache - The Java EE 6 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2011-03-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/javaeetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td width="400px"><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnaph.html">4.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="giepx.html">5.&nbsp;&nbsp;Introduction to Facelets</a></p>
<p class="toc level2"><a href="gjddd.html">6.&nbsp;&nbsp;Expression Language</a></p>
<p class="toc level2"><a href="bnaqz.html">7.&nbsp;&nbsp;Using JavaServer Faces Technology in Web Pages</a></p>
<p class="toc level2"><a href="gjcut.html">8.&nbsp;&nbsp;Using Converters, Listeners, and Validators</a></p>
<p class="toc level2"><a href="bnatx.html">9.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkmaa.html">10.&nbsp;&nbsp;JavaServer Faces Technology Advanced Concepts</a></p>
<p class="toc level2"><a href="bnawo.html">11.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level2"><a href="gkiow.html">12.&nbsp;&nbsp;Using Ajax with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkhxa.html">13.&nbsp;&nbsp;Advanced Composite Components</a></p>
<p class="toc level2"><a href="bnavg.html">14.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnafd.html">15.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnaxu.html">16.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="gijti.html">17.&nbsp;&nbsp;Introduction to Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">18.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="giepu.html">19.&nbsp;&nbsp;Building RESTful Web Services with JAX-RS</a></p>
<p class="toc level2"><a href="gjjxe.html">20.&nbsp;&nbsp;Advanced JAX-RS Features</a></p>
<p class="toc level2"><a href="gkojl.html">21.&nbsp;&nbsp;Running the Advanced JAX-RS Example Application</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijsz.html">22.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijre.html">23.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="gijrb.html">24.&nbsp;&nbsp;Running the Enterprise Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">25.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level2"><a href="gkcqz.html">26.&nbsp;&nbsp;Using the Embedded Enterprise Bean Container</a></p>
<p class="toc level2"><a href="gkidz.html">27.&nbsp;&nbsp;Using Asynchronous Method Invocation in Session Beans</a></p>
<p class="toc level1 tocsp"><a href="gjbnr.html">Part&nbsp;V&nbsp;Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="giwhb.html">28.&nbsp;&nbsp;Introduction to Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="gjbls.html">29.&nbsp;&nbsp;Running the Basic Contexts and Dependency Injection Examples</a></p>
<p class="toc level2"><a href="gjehi.html">30.&nbsp;&nbsp;Contexts and Dependency Injection for the Java EE Platform: Advanced Topics</a></p>
<p class="toc level2"><a href="gkhre.html">31.&nbsp;&nbsp;Running the Advanced Contexts and Dependency Injection Examples</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;VI&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">32.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="gijst.html">33.&nbsp;&nbsp;Running the Persistence Examples</a></p>
<p class="toc level2"><a href="bnbtg.html">34.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level2"><a href="gjitv.html">35.&nbsp;&nbsp;Using the Criteria API to Create Queries</a></p>
<p class="toc level2"><a href="gkjiq.html">36.&nbsp;&nbsp;Creating and Using String-Based Criteria Queries</a></p>
<p class="toc level2"><a href="gkjjf.html">37.&nbsp;&nbsp;Controlling Concurrent Access to Entity Data with Locking</a></p>
<p class="toc level2"><a href="gkjia.html">38.&nbsp;&nbsp;Improving the Performance of Java Persistence API Applications By Setting a Second-Level Cache</a></p>
<div id="scrolltoc" class="onpage">
<p class="toc level3"><a href="">Overview of the Second-Level Cache</a></p>
<p class="toc level4"><a href="#gkjiw">Controlling Whether Entities May Be Cached</a></p>
</div>
<p class="toc level3 tocsp"><a href="gkjjj.html">Specifying the Cache Mode Settings to Improve Performance</a></p>
<p class="toc level4"><a href="gkjjj.html#gkjdk">Setting the Cache Retrieval and Store Modes</a></p>
<p class="toc level5"><a href="gkjjj.html#gkjdr">Cache Retrieval Mode</a></p>
<p class="toc level5"><a href="gkjjj.html#gkjdd">Cache Store Mode</a></p>
<p class="toc level5"><a href="gkjjj.html#gkjds">Setting the Cache Retrieval or Store Mode</a></p>
<p class="toc level4 tocsp"><a href="gkjjj.html#gkjeb">Controlling the Second-Level Cache Programmatically</a></p>
<p class="toc level5"><a href="gkjjj.html#gkjdz">Checking Whether An Entity's Data is Cached</a></p>
<p class="toc level5"><a href="gkjjj.html#gkjdq">Removing an Entity from the Cache</a></p>
<p class="toc level5"><a href="gkjjj.html#gkjda">Removing All Data from the Cache</a></p>
<p class="toc level1 tocsp"><a href="gijrp.html">Part&nbsp;VII&nbsp;Security</a></p>
<p class="toc level2"><a href="bnbwj.html">39.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bncas.html">40.&nbsp;&nbsp;Getting Started Securing Web Applications</a></p>
<p class="toc level2"><a href="bnbyk.html">41.&nbsp;&nbsp;Getting Started Securing Enterprise Applications</a></p>
<p class="toc level1 tocsp"><a href="gijue.html">Part&nbsp;VIII&nbsp;Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="gijto.html">42.&nbsp;&nbsp;Introduction to Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="bncih.html">43.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">44.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncdq.html">45.&nbsp;&nbsp;Java Message Service Concepts</a></p>
<p class="toc level2"><a href="bncgv.html">46.&nbsp;&nbsp;Java Message Service Examples</a></p>
<p class="toc level2"><a href="gkahp.html">47.&nbsp;&nbsp;Advanced Bean Validation Concepts and Examples</a></p>
<p class="toc level2"><a href="gkeed.html">48.&nbsp;&nbsp;Using Java EE Interceptors</a></p>
<p class="toc level1 tocsp"><a href="gkgjw.html">Part&nbsp;IX&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="gkaee.html">49.&nbsp;&nbsp;Duke's Tutoring Case Study Example</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td>
         <div class="header">
             <div class="banner">
                <table width="100%" border="0" cellpadding="5" cellspacing="0">
                   <tbody>
                      <tr>
                         <td valign="bottom"><p class="Banner">The Java EE 6 Tutorial
</p></td>
                         <td align="right"  valign="bottom"><img src="graphics/javalogo.png" alt="Java Coffee Cup logo"></td>
                      </tr>
                   </tbody>
                </table>
             </div>

             <div class="header-links">
	         <a href="./index.html">Home</a> | 
<a href="../information/download.html">Download</a> | 
<a href="./javaeetutorial6.pdf">PDF</a> | 
<a href="../information/faq.html">FAQ</a> | 
<a href="http://download.oracle.com/javaee/feedback.htm">Feedback</a>

             </div>
             <div class="navigation">
                 <a href="gkjia.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
                 <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
                 <a href="gkjjj.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="gkjio"></a><h2>Overview of the Second-Level Cache</h2>
<p>A <b>second-level cache</b> is a local store of entity data managed by the persistence
provider to improve application performance. A second-level cache helps improve performance by avoiding
expensive database calls, keeping the entity data local to the application. A second-level
cache is typically transparent to the application, as it is managed by the
persistence provider and underlies the persistence context of an application. That is, the application
reads and commits data through the normal entity manager operations without knowing about
the cache.</p>


<hr><p><b>Note - </b>Persistence providers are not required to support a second-level cache. Portable applications should
not rely on support by persistence providers for a second-level cache.</p>


<hr>
<p>The second-level cache for a persistence unit may be configured to one of
several second-level cache modes. The following cache mode settings are defined by the
Java Persistence API.</p>

<a name="gkjdg"></a><p class="caption">Table&nbsp;38-1 Cache Mode Settings for the Second-Level Cache</p><table><col width="50%"><col width="50%"><tr><th align="left" valign="top" scope="column"><p>Cache Mode Setting</p>

</th>
<th align="left" valign="top" scope="column"><p>Description</p>

</th>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>ALL</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>All entity data is stored in the second-level
cache for this persistence unit.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>NONE</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>No data is cached in the persistence unit. The
persistence provider must not cache any data.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>ENABLE_SELECTIVE</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Enable caching for entities that have been
explicitly set with the <tt>@Cacheable</tt> annotation.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>DISABLE_SELECTIVE</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Enable caching for all entities except those
that have been explicitly set with the <tt>@Cacheable(false)</tt> annotation.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>UNSPECIFIED</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>The caching behavior for the
persistence unit is undefined. The persistence provider's default caching behavior will be used.</p>

</td>
</tr>
</table><p>One consequence of using a second-level cache in an application is that the
underlying data may have changed in the database tables, but the value in
the cache has not, a circumstance called a <b>stale read</b>. Stale reads may be
avoided by changing the second-level cache to one of the cache mode settings,
controlling which entities may be cached (described in <a href="#gkjiw">Controlling Whether Entities May Be Cached</a>), or changing the cache's
retrieval or store modes (described in <a href="gkjjj.html#gkjdk">Setting the Cache Retrieval and Store Modes</a>). Which strategies best avoid stale reads
are application dependent.</p>



<a name="gkjiw"></a><h3>Controlling Whether Entities May Be Cached</h3>
<p>The <tt>javax.persistence.Cacheable</tt> annotation is used to specify that an entity class, and any
subclasses, may be cached when using the <tt>ENABLE_SELECTIVE</tt> or <tt>DISABLE_SELECTIVE</tt> cache modes. Subclasses may
override the <tt>@Cacheable</tt> setting by adding a <tt>@Cacheable</tt> annotation and changing the value.</p>

<p>To specify that an entity may be cached, add a <tt>Cacheable</tt> annotation at
the class level:</p>

<pre>@Cacheable
@Entity
public class Person { ... }</pre><p>By default, the <tt>@Cacheable</tt> annotation is <tt>true</tt>. The following example is equivalent:</p>

<pre>@Cacheable(true)
@Entity
public class Person{ ... }</pre><p>To specify that an entity must not be cached, add a <tt>@Cacheable</tt>
annotation and set it to <tt>false</tt>:</p>

<pre>@Cacheable(false)
@Entity
public class OrderStatus { ... }</pre><p>When the <tt>ENABLE_SELECTIVE</tt> cache mode is set, the persistence provider will cache any
entities that have a <tt>@Cacheable(true)</tt> annotation and any subclasses of that entity
that have not been overridden. The persistence provider will not cache entities that
have <tt>@Cacheable(false)</tt> or have no <tt>@Cacheable</tt> annotation. That is, the <tt>ENABLE_SELECTIVE</tt> mode will
only cache entities that have been explicitly marked for the cache using the
<tt>@Cacheable</tt> annotation.</p>

<p>When the <tt>DISABLE_SELECTIVE</tt> cache mode is set, the persistence provider will cache any
entities that <b>do not</b> have a <tt>@Cacheable(false)</tt> annotation. Entities that do not have a <tt>@Cacheable</tt>
annotation, and entities with a <tt>@Cacheable(true)</tt> annotation will be cached. That is,
the <tt>DISABLE_SELECTIVE</tt> mode will cache all entities that have not been explicitly
prevented from being cached.</p>

<p>If the cache mode is set to <tt>UNDEFINED</tt>, or is left unset, the
behavior of entities annotated with <tt>@Cacheable</tt> is undefined. If the cache mode is
set to <tt>ALL</tt> or <tt>NONE</tt>, the value of the <tt>@Cacheable</tt> annotation is ignored
by the persistence provider.</p>


         </div>
         <div class="navigation">
             <a href="gkjia.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
             <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
             <a href="gkjjj.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
         </div>

         <div class="copyright">
      	    <p>Copyright &copy; 2011, Oracle and/or its affiliates. All rights reserved. <a href="docinfo.html">Legal Notices</a></p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

